.\" $snafu: gardump.1,v 2.0 2003/10/06 19:14:00 marc Exp $
.\"
.\" Public Domain, 2001, Marco S Hyman <marc@snafu.org>
.\"
.Dd May 7, 1998
.Dt GARDUMP 1
.Os SNAFU\ Software
.Sh NAME
.Nm gardump
.Nd dump waypoints, routes, and tracks from a Garmin GPS unit
.Sh SYNOPSIS
.Nm
.Op Fl vwrtu
.Op Fl d Ar debug-level
.Op Fl p Ar port
.Sh DESCRIPTION
.Nm
will dump (retrieve) waypoint, route, and/or tracking information
from a Garmin GPS unit sending the data to standard out in a
readable format.  The output can be re-directed to a file, massaged
with your favorite text editor, and then sent back to the GPS
unit using the
.Xr garload 1
program.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl v
Display the software version on stderr and exit with a return code of 1.
.It Fl w
Retrieve waypoints and write them to stdout.
.It Fl r
Retrieve routes and write them to stdout.
.It Fl t
Retrieve the track log and write it to stdout.
.It Fl u
Retrieve the 
.Tn UTC
timesamp and write it to stdout.
.It Fl d Ar debug-level
Enable various levels of debugging output.  Without this option
debugging is disabled and only critical errors are written to
stderr.  Additional debug output at the various levels are:
.Bl -tag -width Ds
.It 1
Write all error messages to stderr.
.It 2
Write status messages to stderr.
.It 3
Write Garmin application protocol status to stderr.
.It 4
Perform a dump of all data going in and out of the Garmin
layer 2 protocol machine.  Data sent to the
.Tn GPS
is prefixed by the symbol
.Li } .
Data received from the
.Tn GPS
is prefixed by the symbol
.Li { .
Data is written to stderr.
.It 5
Perform a dump of all data read from/written to the GPS unit.
Data sent to the
.Tn GPS
is prefixed by the symbol
.Li > .
Data received from the
.Tn GPS
is prefixed by the symbol
.Li < .
Data is written to stderr.
.El
.It Fl p Ar port
Use
.Ar port
as the device connected to the GPS unit.  The default port is a
compile time option that is typically set to
.Pa /dev/tty00 .
.El
.Pp
If no options are given
.Nm
will retrieve the
.Tn UTC
time, waypoints, routes, and tracks, in that order.  All
are written to stdout.
.\".Sh ENVIRONMENT
.\".Sh FILES
.Sh EXAMPLES
The command:
.Bd -literal -offset indent
gardump -w

.Ed
results in the output
.Bd -literal -offset indent
[gardump version 1.93]
[product 155, version 207: GPS 5 Software Version 2.07]
[waypoints, 3 records]
# **n [route name]
# lat long [A:alt] [S:sym] [D:display] [I:id] [C:cmnt] [W:wpt info] [L:link]
 37.109129 -121.016012 S:18 I:ANDRSN C:ANDERSEN'S SPLIT PEA
 36.524042 -118.765690 S:18 I:BCKEYE C:HWY 198
 38.667026 -120.122119 S:18 I:SILVER C:SILVER LAKE
[end transfer, 3/3 records]

.Ed
.\".SH DIAGNOSTICS
.Sh SEE ALSO
.Xr garload 1
.\".Sh HISTORY
.Sh AUTHORS
Marco S. Hyman using information from the published GARMIN GPS Interface
Specification, dated December 6, 1999 and the note OBSERVATIONS OF THE
GARMIN-GARMIN PROTOCOL by william.soley@sun.com and werme@zk3.dec.com.
.Sh BUGS
Tested with a Garmin GPS III+ and GPS V using OpenBSD versions
2.3 through 3.3 running on SPARC and i386.  May not work with other
GPS units or operating systems
